home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / src / exampleCode / opengl / toogl / README < prev    next >
Text File  |  1996-11-11  |  6KB  |  210 lines
  1. /*
  2.  * Copyright (c) 1992, 1993 Silicon Graphics, Inc.
  3.  *
  4.  * Permission to use, copy, modify, distribute, and sell this software and
  5.  * its documentation for any purpose is hereby granted without fee, provided
  6.  * that (i) the above copyright notices and this permission notice appear in
  7.  * all copies of the software and related documentation, and (ii) the name of
  8.  * Silicon Graphics may not be used in any advertising or publicity relating 
  9.  * to the software without the specific, prior written permission of 
  10.  * Silicon Graphics.
  11.  *
  12.  * THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF
  13.  * ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, 
  14.  * ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  15.  *
  16.  * IN NO EVENT SHALL SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, 
  17.  * INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER 
  18.  * RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF 
  19.  * THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT 
  20.  * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  21.  */
  22.  
  23. Toogl (TO OpenGL) is a program to translate Iris GL programs into OpenGL
  24. programs.
  25.  
  26. Usage: toogl [-clLqwv] < infile > outfile
  27.         -c  don't put comments with OGLXXX into program
  28.         -l  don't translate lighting calls (e.g. lmdef, lmbind, #defines) 
  29.         -L  translate lighting calls for emulation library (mylmdef, mylmbind) (implies -l) 
  30.         -q  don't translate event queue calls (e.g. qread, setvaluator) 
  31.         -v  print revision number.
  32.         -w  don't translate window manager calls (e.g. winopen, mapcolor) 
  33.  
  34. Typical usage might be like this:
  35.  
  36. #!/bin/sh
  37. mkdir OpenGL
  38. for i in *.c
  39.     do
  40.     echo $i
  41.     toogl < $i > OpenGL/$i
  42.     done
  43.  
  44. You should most definitly KEEP YOUR ORIGINAL SOURCE. Use a directory
  45. like the above shell script or use RCS:
  46.  
  47. #!/bin/sh
  48. for i in *.c
  49.     do
  50.     ci -fm"check in for toogl" $i < /dev/null
  51.     co -lp $i | toogl  > $i
  52.     done
  53.  
  54.  
  55. That's it. It's a filter that scans each line of infile looking for
  56. IrisGL stuff. When it finds an IrisGL function, it replaces it with the
  57. corresponding OpenGL function(s). It attempts to fix up arguments where
  58. it can. Many IrisGL #defines from gl.h are also translated into
  59. equivalent OpenGL defines where possible. You will need to edit the
  60. results and probably use gdiff to figure things out.
  61.  
  62. Any time toogl does something that I thought you might need to look at,
  63. check, or change, it outputs a comment with "OGLXXX" in it. These come
  64. out before the line in question and you may search for them with your
  65. editor.  Use the -c option if you don't want the comments.
  66.  
  67. Toogl can help with translation of lighting commands (lmdef, lmbind,
  68. and data structures), but it's not perfect. The -L option will cause
  69. toogl to translate lmdef and lmbind into commands for the emulation
  70. library in irisgl_light.c
  71.  
  72. Toogl goes wild on sections of code where you make window manager,
  73. window configuration, device, and event calls. You're going to have to
  74. re-write these yourself until some compatibility library comes along.
  75. Using the -w and -q options will leave this code alone so you can still
  76. read it to translate it manually.
  77.  
  78. Toogl understands a little about matching parentheses and quotes:
  79.  
  80.     v3f( v[strlen(strcat(foo, "foo("))] );
  81.  
  82.  
  83. translates into:
  84.  
  85.         glVertex3fv( v[strlen(strcat(foo, "foo("))] );
  86.       
  87.  
  88. PROBLEMS:
  89.  
  90. 1) Toogl expects to find the matching parentheses or quotes ON THE SAME LINE
  91. as the IrisGL function:
  92.  
  93.     v3f( foo 
  94.         ); 
  95.  
  96. won't work. This will probably generate an warning message and the function
  97. won't be changed.
  98.  
  99.  
  100. 2) Toogl expects to find only <space> and <tab> characters between the 
  101. function name and the '(':
  102.  
  103.     v3f
  104.         (foo);
  105.  
  106. will be left un-changed, as will:
  107.  
  108.     v3f /* comment */ (foo);
  109.  
  110.  
  111. 3) C comments inside the argument list of a function shouldn't contain 
  112. parentheses or quote characters. e.g:
  113.  
  114.     v3f ( foo /* I really mean bar "-) */ );
  115.  
  116. will generate a warning and be un-changed.
  117.  
  118.  
  119. 4) "Gets" in IrisGL were of the form:
  120.  
  121.  
  122.     int getthing();
  123.  
  124.     int getthings( int *a, int *b);
  125.  
  126. and y'all write code like:
  127.  
  128.     thing = getthing();
  129.  
  130.     if(getthing() == THING) {
  131.     }
  132.  
  133.     getthings (&a, &b);
  134.  
  135. "Gets" in OpenGL are of the form:
  136.  
  137.     void glGetIntegerfv(NAME_OF_THING, &thing);
  138.  
  139. Toogl does the best it can:
  140.  
  141.     i = getcolor();
  142.  
  143.     getdepth(&near, &far);
  144.  
  145. will translate into:
  146.  
  147.  
  148.     /* OGLXXX
  149.      * getshade:
  150.      * GLint gctmp;
  151.      */
  152.     i = (glGetIntegerv(GL_CURRENT_INDEX, &gstmp), gstmp);
  153.  
  154.     /* OGLXXX You can probably do better than this. */
  155.     {
  156.         int    get_depth_tmp[2];
  157.         glGetIntegerv(GL_DEPTH_RANGE, get_depth_tmp);
  158.         *(&near) = get_depth_tmp[0];
  159.         *( &far) = get_depth_tmp[1];
  160.     };
  161.  
  162.  
  163. 5) "lmdef" and "texdef" are close to impossible to deal with. The parameter lists
  164. are translated and commented and the function calls are mangled. See the
  165. -l and -L options for lighting. No such code currently exists for texture.
  166.  
  167. 6) Toogl does all the translation on ONE LINE. I've re-formatted the stuff above
  168. to make it readable. The comments do come out as shown. You may want to use cb.
  169. If you do, you may want to "cb" your code before using toogl, so gdiff
  170. will only show changes due to toogl and not ones due to cb. Note that cb 
  171. isn't perfect, either.
  172.  
  173. 7) This space intentionally left almost blank.
  174.  
  175. 8) (BUG) stuff inside quotes and comments is scanned, too.
  176.  
  177.     printf("scale (reason %d)", reason); 
  178.  
  179. causes a non-fatal error message. (Looks like a call to scale with one argument).
  180.  
  181. 9) You'll need to change #include <gl.h> into #include <GL/gl.h>
  182. This sed script may be of help:
  183.  
  184. sed -e 's@^#[   ]*include[       ]*[<"][^">]*[/]*gl.h[">]@#include "GL/gl.h"@' < in  > out
  185.               ^^ tab       ^^ tab
  186.  
  187. 10) There is 1 warning message during compilation: optimization won't
  188. help this routines that are too big.
  189.  
  190. 11) (BUG) toogl translates stuff in comments and likely screws up the comment 
  191. in the process:
  192.  
  193.  
  194.     /* 
  195.      i = getcolor(); 
  196.      */
  197.  
  198.  
  199. (incorrectly) translates into:
  200.  
  201.  
  202.         /* 
  203.         /* OGLXXX
  204.          * getshade:
  205.          * GLint gctmp;
  206.          */
  207.          i = (glGetIntegerv(GL_CURRENT_INDEX, &gstmp), gstmp); 
  208.          */
  209.  
  210.